Language/OS - Multiplatform Resource Library/LANGUAGE OS.iso/cpp_libs/tools/cie.lha/cie/README

Text File | 1993-06-22 | 9.2 KB | 197 lines

C++ In Emacs (CIE) v 1.0

Archive-name: cie
Environment: Emacs, C++

Author:  Brian M Kennedy ([e-mail])
         with contributions from:
           Walt Buehring (tags.el and minibuffer-yank.el)
           Sam Kendall (tags.el)
       (and, of course, the original tags.el author(s)).


This package is a collection of some of the tools/enhancements we use for C++
development work within GNU Emacs.  Briefly, it consists of an enhanced etags
for C++, a related class hierarchy generator, a mode and M-x commands for
browsing the hierarchy and getting lists of class members, a command goto-file
that takes you to the proper line in a file, functions to make both tag names
and file names mouseable, and a class manual generator that uses the hierarchy
and tag information, coupled with the comments in the code, to build a class
manual in texinfo format.

I've been stalling on releasing this, hoping to find time to implement some of
the outstanding features and do some significant cleanup.  I have decided that
I will never get to it (and I feel more and more guilty every time I see one
of the many requests for these features on the newsgroups), so I am just going
to release it basically as is.  My apologies.

Note the implication here -- in the past many, many months I have never found
time to do any of the to-do queue.  You are welcome to send bug reports and
suggestions, but it is highly improbable that I will ever manage to get to
acting on them.  If you like this package, and want it to grow, consider
volunteering to adopt it and become its maintainer.  Any and all are welcome
to do so.

This has run with GNU Emacs 18.51, 18.55, 18.57 and 18.58.  I have not yet
switched to Emacs 19, so neither has this code.  If you want to use it with
Emacs 19, I encourage you to volunteer to "port" it for the rest of us ;-)

The etags++ and hier++ C++ programs have been compiled with Sun C++,
Centerline C++, Lucid C++, and Comeau C++ on Sun OS, Ultrix, and AIX
platforms.

=====

The directory etags++ contains source for two programs, etags++ and hier++.
They are written in C++.  Assuming you have some reasonable C++ compiler
accessible via command "CC", a simple make should build the two programs.

The file do-etags++ is simply an example of how to invoke etags++, hier++,
and emacs in batch mode to save out the tags-alist.  This is done for me
automatically each night (but just takes a few minutes on 100K LOC).

The files cie.el and cie-mouse.el set up keystrokes and mousestrokes and
autoloads for the other files.  You may want to load these (or variations)
in your default.el or .emacs.

The other files (the meat) need to be dropped in your load-path somewhere.
Note that the tags.el should be loaded instead of (or after) the standard
tags.el.

The TAGS file generated by etags++ is standard format.  So, it is possible
to use just that with the standard tags.el.  And this tags.el should work
essentially the same as the standard tags.el on TAGS files generated by the
standard etags program (that is important since etags++ only supports C/C++
code; you must use the standard etags for Lisp, TeX, FORTRAN, etc.).


Here are excerpts from the important files:

======================
;;; tags.el

;; INTELLECTION MODS:
;;
;; 1) Prefers the tags named explicitly after C-A's at the end of each line.
;;    This is true both for find-tag and for the completion-alist.
;; 2) Support for C++ scoping -- class::name is considered a tag and both
;;    class::name and name are matches (class::name preferred though).
;; 3) Support for completion of scoped names as well as unscoped names.
;;    That is, the alist contains both the fully-scoped name, and each
;;    subname (c1::c2::mem => c1::c2::mem, c2::mem, and mem in the alist).
;; 4) Added mechanism to save out the completion alist into TAGS.alist
;;    which is checked for when loading TAGS to prevent the need to rebuild
;;    the alist (which can take a while with large systems).  As an added
;;    advantage, this mechanism removes duplicates from the alist before
;;    saving it out (making it faster and much smaller).

======================
;;; hier-mode.el
;;; Hierarchy mode (for hierarchies output by hier++)

"Major mode for viewing class hierarchy files output by hier++.
The file is formatted like this:

* class_a
  * child_b  :class_a
  * child_c  :class_a :class_f
    * grandchild_d  :child_c
    * grandchild_e  :child_c
* class_f
  * child_c  :class_a :class_f
    * grandchild_d  :child_c
    * grandchild_e  :child_c
  * child_g  :class_f

Classes child_b and child_c are derived from class_a; classes child_c and
child_g are derived from class_f; classes grandchild_d and grandchild_e are
both derived from child_c.  Note that each class (and all of its children)
will appear in the file once under each parent.

Defined keys:
M-p moves to the previous sibling
M-n moves to the next sibling
M-u moves up to the parent
M-h finds the first occurrence of the hierarchy element for a class
    (similar to M-. in behavior)
M-g finds the next occurrence (like M-,) in the case of multiple-inheritance.
M-m brings up a new window with a listing of all the members (both direct and
    inherited) of that hierarchy entry.  It does this via tags, so you must
    have tags set up in Emacs.  It will also only work properly if the tags
    file was generated by etags++ (companion to hier++)."

======================
;;; class-manual.el
;;; Class Manual Generation
;;;   Code to use hier-mode (for hierarchies output by hier++) and etags++
;;;   functionality to build a class manual using the header comments in
;;;   the code itself.  The formatting is in standard texinfo.
;;;   This is a hack that has been helpful for us, given our coding
;;;   guidelines.  It will likely need modification to produce good
;;;   output for you.  (Header comments are those placed between the
;;;   signature and the body of functions or classes.  If you don't follow
;;;   this convention, then this code will need modification.)

======================
;;; goto-file.el

;;; By binding goto-file to a key or mouse stroke, you can essentially
;;; make filenames "hot"; it will attempt to find that file in the
;;; current buffer's default directory.  If no such file exists, then
;;; it checks the current tags-table, gambling that it is one of your
;;; source files and will be tagged.
;;;
;;; Furthermore, it will try to go to the right location in the file.
;;; If there is an adjacent line number, then it will go to that line.
;;; Or if there is an adjacent grep pattern, then it will find that pattern.
;;;
;;; For instance, if you are in a shell and do an "ls", you can then click on
;;; any file name to open the file.  If you do a "make", you can click on any
;;; error msg to take you to the line of the error.  If you are in dbx, and it
;;; outputs a break or an assert outputs file/line, then you can simply click
;;; on the filename to take you to the line.  If you do a "grep", then you
;;; can simply click on the filename of the match that you want to go to.
;;; IMO, this is preferable to M-x compile or grep, because there is no need
;;; to proceed in order.  It also works everywhere: in source files, in
;;; shells, in night build logs, in mail buffers, etc.

======================
// etags++/c++file.c
//
// This .c file, written in C++, is intended to be included in etags++.c and hier++.c.
// It is a quick-and-dirty "fuzzy" parser for C++ files that identifies enough tokens for
// etags++ and hier++ to do a good job.  See those files for information on the resultant
// functionality.  This file simply provides the common parsing code.

======================
// etags++/etags++.c
//
// This program reads in C++ code and generates a tags file for GNU Emacs.
// This program is more sophisticated than the standard etags program for C++
// programs.  It finds all classes, structs, unions, enums, enumerators, #defines,
// typedefs, functions (both global and member), and data (both global and member).
// Furthermore, it handles C++ scoping correctly, outputting fully-scoped tags
// at the end of each line.  Thus, we have modified our Emacs tags.el to search
// the fully-scoped names at the ends of the lines before the patterns.  It also
// handles template syntax.
//
// In addition, we have added support for a few important macro conventions that
// we use.  DECLARE_*(name,..) macros define the tag <name> in the current scope;
// DEFINE_*(class,name,...) macros define the tag <class>::<name>.  We use NOTE(name)
// macros to name comments, so that you can refer to them by See::name in other
// comments.  In Emacs, M-. on See::name will take you to the named comment.
//
// Note that this uses "fuzzy", quick-and-dirty parsing to find the tokens.  Thus, it
// can miss some things.  Also note that this is not an etags replacement -- it only
// supports C/C++ code.  The etags program will still be needed for TeX, Fortran, etc.

======================
// etags++/hier++.c
//
// This program reads in C++ code and generates a "hier" file that displays the
// class hierarchy.  You can then use the GNU Emacs hier-mode for traversing the
// hierarchy and extracting information from your TAGS (if generated by etags++).
//
// Note that this program is built on the same quick-and-dirty "fuzzy" parser
// that etags++ was, and will suffer the same ability to be fooled sometimes.